Where Does Claude Code Store Memory? Complete Guide to CLAUDE.md Files

Posted May 16, 2026 · 6 min read

If you've been using Claude Code for any length of time, you've probably noticed it remembers things between sessions — your coding style, project conventions, decisions you've explained once. That memory lives in plain Markdown files on your machine. This guide explains exactly where they live, how the hierarchy works, and the most ergonomic way to browse and edit them on macOS.

The Three Layers of Claude Code Memory

Claude Code uses a layered memory system. From most-specific to most-general:

When Claude Code starts a session, it loads all of these in order from most-specific to most-general. Earlier rules win on conflict.

The ~/.claude/ Directory in Detail

On macOS your global Claude Code data lives at ~/.claude/. The relevant files:

~/.claude/
├── CLAUDE.md              # Your global preferences (you edit)
├── projects/              # Per-project auto-memory (Claude writes)
│   └── -Users-you-Projects-app/
│       └── memory/
│           ├── MEMORY.md          # Index of memory files
│           └── 2026-05-16.md      # Daily memory log
├── settings.json          # User settings
└── projects/.../sessions/ # Per-session transcripts (JSONL)

The memory/ folders are particularly interesting — they accumulate over weeks of work and become a real "second brain" for each project. Reviewing them periodically often reveals patterns you didn't realize Claude had picked up.

Project-Level CLAUDE.md

Drop a CLAUDE.md in any project root and Claude Code will load it whenever you work in that directory. Useful contents:

• Build/test commands and how to run them
• Naming conventions specific to this codebase
• Architectural decisions and tradeoffs Claude shouldn't re-litigate
• Known landmines ("don't touch the legacy auth module without checking with X")
• Coding style preferences (formatter quirks, comment policy, etc.)

Claude Code also looks for CLAUDE.md in parent directories. If you have several related projects under ~/code/myorg/, drop a CLAUDE.md there with org-wide conventions and every sub-project inherits them.

How to Read and Edit These Files Efficiently

The naive way: open them in a text editor. The problem is they grow into hundreds of lines, are pure Markdown (so renderless plain text is ugly), and aren't always in obvious places.

Three ergonomic options:

1. Native Mac/iOS app — AI Memory Reader

The tool this guide ships with. Auto-detects ~/.claude/ (and 7 other AI tool dirs), renders Markdown beautifully, lets you search and edit. Free, GPL-3.0.

2. claude-mem — CLI/web dashboard

If you prefer a terminal/web workflow, claude-mem compresses session activity into structured memory and provides a local dashboard.

3. Just cat + a markdown CLI renderer

For the minimalist: cat ~/.claude/CLAUDE.md | glow - or cat ~/.claude/CLAUDE.md | mdcat.

A Few Tricks Worth Knowing

• Run /memory inside Claude Code to see exactly which memory files Claude has loaded for the current session, in order.
• Use CLAUDE.local.md for personal scratch notes Claude should see but your team shouldn't. It's gitignored by Claude Code's default templates.
• Don't over-write CLAUDE.md. Concise rules with why beat long lists of what. Claude is smarter than you'd think — give it principles, not micromanagement.
• Auto-memory in memory/YYYY-MM-DD.md is Claude's daily journal. It's append-only and growing — periodically distill the useful patterns into your main CLAUDE.md.

Related AI Tool Memory Locations

If you use other AI coding agents, here's where their memory lives on macOS: